%% Log Minus
% by Jaromir Benes
%
% This tutorial shows how to construct models with variables that need to
% be log-linearised (because they are growing at a constant rate in steady
% state) but whose sign in steady state is either negative or cannot be
% decided ex ante (they can take either a positive or negative steady-state
% value).
%
% There are two important limitations when dealing with log variables.
% First, log variables can be either positive or negative in steady state,
% but never zero. Swcond, log variables never flip signs in simulations or
% filters by construction: log variables with positive steady state remain
% always positive, log variables with negative steady state remain always
% negative.

%% How to Best Run This Tutorial?
%
% Each m-file in this tutorial is split into what is called "code sections"
% in Matlab. A code cell is a shorter block of code performing a specific
% task, separated from other code cells by a double percent sign, `%%`
% (usually with a title and brief introduction added). By default, the
% cells are visually separated from each other by a horizontal rule in the
% Matlab editor.
%
% Instead of running each m-file from the command window, or executing this
% `read_me_first` as a whole, do the following. Open one tutorial m-file in
% the Matlab editor. Arrange the editor window and the command window next
% to each other so that you can see both of them at the same time. Then run
% the m-file cell by cell. This will help you watch closely what exactly
% is going on.
%
% To execute one particular cell, place the cursor in that cell (the
% respective block of code will get highlighted), and select "Run Current
% Section" from a contextual menu (upon a right click on the mouse), or
% pressing a keyboard shortcut (which differ on different systems and
% Matlab versions). To learn more on code sections, search Matlab
% documentation for "code section".

clc;

%% Simple Model of Open Economy with Non-Zero Net Assets
%
% This model file describes a simple open economy model. The net asset
% position of the economy, `B`, can be either positive or negative, and is
% growing in steady state (i.e. along a balanced-growth path) as the real
% economy grows (because of the productivity process). Therefore, `B` must
% be declared as log variable. This poses no problem even if `B` is
% negative in steady state.

edit log_minus.model;

%% Simple Model of Open Economy with Non-Zero Net Assets: Flip Sign of B
%
% This is the same model as in `log_minus.model` except that the variable
% `B` (net asset position) is replaced with `mB` so that `mB := -B`.

edit log_minus_flip_sign.model;

%% Read Model and Compute Steady State and Solution
%
% In this file, we create two versions of the same model. One version will
% be parameterized so that the variable `B` (net assets) will be positive
% whereas the other version will have `B` negative. In both models, `B`
% will be a log variable.
%
% Models with negative log variables can be thought of as identical models
% in which we replace the negative log variable with its

% edit read_model.m;
read_model;

%% Read Model with the Sign Flipped
% 
% In this file, we show that models with negative log variables behave
% exactly the same as models in which we flip the sign of these variables
% (creating thus positive log variables).

% edit read_model_flip_sign.m;
read_model_flip_sign;

%% Simulate Permanent Endowment Shock
%
% We simulate the same (endowment) shock in three model objects and compare
% the simulation results: a model with a positive asset position, with a
% negative asset position, and a model with a negative asset position but
% with the sign of the asset position variable flipped. We perform the
% simulations using both of the two methods available in IRIS: "deviations
% from control" and in "full levels".

% edit simulate_endowment_shock.m;
simulate_endowment_shock;

%% Publish Tutorial Files to PDFs
%
% The following commands can be used to create PDF versions of the tutorial
% files:

%{
    latex.publish('read_me_first.m',[],'evalCode=',false);
    latex.publish('log_minus.model');
    latex.publish('log_minus_flip_sign.model');
    latex.publish('read_model.m');
    latex.publish('read_model_flip_sign.m');
    latex.publish('simulate_endowment_shock.m');
%}
